home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / fx / dmFXDrawPixels.z / dmFXDrawPixels
Encoding:
Text File  |  2002-10-03  |  14.3 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss((((3333ddddmmmm))))                                        ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss, ddddmmmmFFFFXXXXCCCCoooonnnnvvvvoooollllvvvveeee, ddddmmmmFFFFXXXXSSSSccccaaaalllleeeeBBBBiiiiaaaassss, ddddmmmmFFFFXXXXMMMMaaaattttrrrriiiixxxxMMMMuuuullllttttiiiippppllllyyyy - pixel
  10.      transfer operations for special effects
  11.  
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ffffxxxx____bbbbuuuuffffffffeeeerrrr....hhhh>>>>
  15.  
  16.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss
  17.            (((( PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnn,,,,
  18.              iiiinnnntttt xxxxPPPPoooossssiiiittttiiiioooonnnn,,,,
  19.              iiiinnnntttt yyyyPPPPoooossssiiiittttiiiioooonnnn,,,,
  20.              PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ssssoooouuuurrrrcccceeee,,,,
  21.              iiiinnnntttt xxxxOOOOffffffffsssseeeetttt,,,,
  22.              iiiinnnntttt yyyyOOOOffffffffsssseeeetttt,,,,
  23.              iiiinnnntttt wwwwiiiiddddtttthhhh,,,,
  24.              iiiinnnntttt hhhheeeeiiiigggghhhhtttt ))))
  25.  
  26.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmFFFFXXXXCCCCoooonnnnvvvvoooollllvvvveeee
  27.            (((( PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnn,,,,
  28.              PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ssssoooouuuurrrrcccceeee,,,,
  29.              iiiinnnntttt mmmmaaaattttrrrriiiixxxxWWWWiiiiddddtttthhhh,,,,
  30.              iiiinnnntttt mmmmaaaattttrrrriiiixxxxHHHHeeeeiiiigggghhhhtttt,,,,
  31.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt**** mmmmaaaattttrrrriiiixxxx,,,,
  32.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt bbbbiiiiaaaassss,,,,
  33.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt ssssccccaaaalllleeee ))))
  34.  
  35.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmFFFFXXXXSSSSccccaaaalllleeeeBBBBiiiiaaaassss
  36.            (((( PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnn,,,,
  37.              PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ssssoooouuuurrrrcccceeee,,,,
  38.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt rrrreeeeddddSSSSccccaaaalllleeee,,,,
  39.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt rrrreeeeddddBBBBiiiiaaaassss,,,,
  40.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt ggggrrrreeeeeeeennnnSSSSccccaaaalllleeee,,,,
  41.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt ggggrrrreeeeeeeennnnBBBBiiiiaaaassss,,,,
  42.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt bbbblllluuuueeeeSSSSccccaaaalllleeee,,,,
  43.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt bbbblllluuuueeeeBBBBiiiiaaaassss,,,,
  44.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt aaaallllpppphhhhaaaaSSSSccccaaaalllleeee,,,,
  45.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt aaaallllpppphhhhaaaaBBBBiiiiaaaassss ))))
  46.  
  47.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmFFFFXXXXMMMMaaaattttrrrriiiixxxxMMMMuuuullllttttiiiippppllllyyyy
  48.            (((( PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ddddeeeessssttttiiiinnnnaaaattttiiiioooonnnn,,,,
  49.              PPPPRRRRXXXX____SSSSccccaaaannnnlllliiiinnnneeeeBBBBuuuuffffffffeeeerrrr ssssoooouuuurrrrcccceeee,,,,
  50.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt**** mmmmaaaattttrrrriiiixxxx,,,,
  51.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt bbbbiiiiaaaassss,,,,
  52.              ccccoooonnnnsssstttt GGGGLLLLffffllllooooaaaatttt ssssccccaaaalllleeee ))))
  53.  
  54.  
  55. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  56.      These two parameters are common to all of these functions.  The other
  57.      parameters are described below in the sections on the different
  58.      functions.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss((((3333ddddmmmm))))                                        ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      _d_e_s_t_i_n_a_t_i_o_n   The image buffer into which pixels are copied.
  75.  
  76.  
  77.      _s_o_u_r_c_e        The image buffer from which pixels are copied.
  78.  
  79.  
  80. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  81.      All of these functions copy pixels from one image buffer to another.
  82.      They make it easy to do common image processing operations without having
  83.      to set up all of the proper OpenGL state. They also correctly compensate
  84.      for the fact that video images are stored top-to-bottom in memory,
  85.      instead of the usual OpenGL bottom-to-top orientation.
  86.  
  87.      All these routines assume that the destination buffer has the standard
  88.      coordinate system that is set up by ddddmmmmFFFFXXXXSSSSeeeettttuuuuppppOOOOuuuuttttppppuuuuttttIIIImmmmaaaaggggeeeeBBBBuuuuffffffffeeeerrrr, with
  89.      (0,0) at the lower-left, and (width,height) at the upper-right.
  90.  
  91.      The values of _G_L__U_N_P_A_C_K__R_O_W__L_E_N_G_T_H, _G_L__U_N_P_A_C_K__S_K_I_P__R_O_W_S,
  92.      _G_L__U_N_P_A_C_K__S_K_I_P__P_I_X_E_L_S, and _G_L__U_N_P_A_C_K__A_L_I_G_N_M_E_N_T may all be changed by
  93.      these functions.
  94.  
  95.      ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss copies a rectangular block of pixels from the source to
  96.      the destination, unmodified.  _x_P_o_s_i_t_i_o_n and _y_P_o_s_i_t_i_o_n are the coordinates
  97.      of the lower-left corner of the rectangle in the destination where the
  98.      pixel will be placed. Any rectangular portion of the source buffer can be
  99.      copied.  The rectangle is specified by _x_O_f_f_s_e_t and _y_O_f_f_s_e_t (the lower-
  100.      left corner), and _w_i_d_t_h and _h_e_i_g_h_t.
  101.  
  102.      ddddmmmmFFFFXXXXCCCCoooonnnnvvvvoooollllvvvveeee copies the entire source buffer to the destination, applying
  103.      an arbitrary 2D convolution matrix, _m_a_t_r_i_x.  The size of the matrix is
  104.      specified by _m_a_t_r_i_x_W_i_d_t_h and _m_a_t_r_i_x_H_e_i_g_h_t, and _m_a_t_r_i_x points to a 2-
  105.      dimensional array of coefficients indexed with coordinates i,j such that
  106.      i increases from left to right and j increases from bottom to top. The
  107.      same convolution matrix is applied equally to the R, G, B, and A
  108.      components of each pixel.  After each component of each pixel is computed
  109.      (by the matrix multiplication), it is multiplied by _s_c_a_l_e and offset by
  110.      _b_i_a_s. The resulting pixel values are clamped to the range from 0.0 to
  111.      1.0.  If the matrix size given exceeds the maximum allowed by OpenGL,
  112.      _D_M__F_A_I_L_U_R_E is returned, and the error code is set to
  113.      _F_X__E_R_R_O_R__C_O_N_V__K_E_R_N_E_L__S_I_Z_E.
  114.  
  115.      ddddmmmmFFFFXXXXSSSSccccaaaalllleeeeBBBBiiiiaaaassss copies the entire source buffer to the destination,
  116.      applying a color correction.  Each component of each pixel is multiplied
  117.      by a scale (_r_e_d_S_c_a_l_e, _g_r_e_e_n_S_c_a_l_e, _b_l_u_e_S_c_a_l_e, or _a_l_p_h_a_S_c_a_l_e) and the
  118.      offset by a bias (_r_e_d_B_i_a_s, _g_r_e_e_n_B_i_a_s, _b_l_u_e_B_i_a_s, or _a_l_p_h_a_B_i_a_s).  The
  119.      resulting values are clamped to the range from 0.0 to 1.0.
  120.  
  121.      ddddmmmmFFFFXXXXMMMMaaaattttrrrriiiixxxxMMMMuuuullllttttiiiippppllllyyyy performs a more general color correction than
  122.      ddddmmmmFFFFXXXXSSSSccccaaaalllleeeeBBBBiiiiaaaassss.  The four components of each pixel are treated as a 4-
  123.      element vector and multiplied by a 4x4 matrix (_m_a_t_r_i_x) to produce new
  124.      values for the four components, then the resulting components are each
  125.      multiplied by _s_c_a_l_e and offset by _b_i_a_s:
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss((((3333ddddmmmm))))                                        ddddmmmmFFFFXXXXDDDDrrrraaaawwwwPPPPiiiixxxxeeeellllssss((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.          RRRR'''' ==== ((((((((mmmm1111 **** RRRR)))) ++++ ((((mmmm5555 **** GGGG)))) ++++  ((((mmmm9999 **** BBBB)))) ++++ ((((mmmm11113333 **** AAAA)))))))) **** RRRRssssccccaaaalllleeee ++++ RRRRbbbbiiiiaaaassss
  141.          GGGG'''' ==== ((((((((mmmm2222 **** RRRR)))) ++++ ((((mmmm6666 **** GGGG)))) ++++ ((((mmmm11110000 **** BBBB)))) ++++ ((((mmmm11114444 **** AAAA)))))))) **** GGGGssssccccaaaalllleeee ++++ GGGGbbbbiiiiaaaassss
  142.          BBBB'''' ==== ((((((((mmmm3333 **** RRRR)))) ++++ ((((mmmm7777 **** GGGG)))) ++++ ((((mmmm11111111 **** BBBB)))) ++++ ((((mmmm11115555 **** AAAA)))))))) **** BBBBssssccccaaaalllleeee ++++ BBBBbbbbiiiiaaaassss
  143.          AAAA'''' ==== ((((((((mmmm4444 **** RRRR)))) ++++ ((((mmmm8888 **** GGGG)))) ++++ ((((mmmm11112222 **** BBBB)))) ++++ ((((mmmm11116666 **** AAAA)))))))) **** AAAAssssccccaaaalllleeee ++++ AAAAbbbbiiiiaaaassss
  144.  
  145.      Finally, each component is clamped to the range from 0.0 to 1.0.
  146.  
  147.  
  148. PPPPIIIIXXXXEEEELLLL ZZZZOOOOOOOOMMMM
  149.      The functions all assume that the modelview matrix has been set up so
  150.      that the coordinate system for the full output image has (0,0) at the
  151.      lower-left corner and (width,height) at the upper-right corner.  They
  152.      also assume that the screen coordinates are the same.  In other words,
  153.      they assume that the pixel zoom (see ggggllllPPPPiiiixxxxeeeellllZZZZoooooooommmm) has been set so that
  154.      using glDrawPixels to draw a full-sized image at (0,0) will exactly fill
  155.      the render area with the image.  If (0,0) is at the upper-left of the
  156.      viewport, then the Y pixel zoom should be negative.
  157.  
  158.  
  159.      During preview, applications may be rendering the results of plug-ins
  160.      directly to the screen, and may not be rendering full-size.  This is
  161.      allowed as long as the pixel zoom is set to meet the above criteria.
  162.  
  163.  
  164.      IIIIMMMMPPPPOOOORRRRTTTTAAAANNNNTTTT:::: It is highly recommended that plug-in authors use these
  165.      functions whenever doing pixel-oriented operations, because they
  166.      correctly handle drawing images upside-down and they correctly handle
  167.      pixel zoom.
  168.  
  169.  
  170. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  171.      dmFXSetupInputImageBuffer(3dm), dmFXSetupScanlineBuffer(3dm),
  172.      dmFXIsGLExtensionSupported(3dm), dmGetError(3dm).
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.